class: center, middle, inverse, title-slide .title[ # Package your Knowledge! ] .subtitle[ ## Mainstream documentation and test with {fusen} ] .date[ ### <a href="index.html"><i class="fa fa-indent fa-fw fa-2x"></i></a> ] --- # Learning objectives * Why creating packages? * How to transition from functions to packages, * Why documentation is crucial * Most current issues to fix package check --- ## Why Create Packages? __Code Organization__ * Packages are a collection of functions, data, and documentation that group related functions and data into a single unit. * They help you organize your code. __Code Reusability__ * A package can be easily shared and used across different projects. * Share your work with others or your future self. * Functions and datasets are easily accessible. __Collaboration__ * Share your packages with the R community. * Contribute to the R ecosystem. --- ## Package Directory Structure ``` MyPackage/ |-- R/ | |-- my_function.R |-- data/ | |-- data_made_available_with_the_package.Rda |-- data-raw/ | |-- data_used_for_package_development.csv |-- inst/ | |-- file_to_be_access_by_the_package.R | |-- man/ | |-- my_function.Rd |-- docs/ | |-- index.html | |-- DESCRIPTION |-- NAMESPACE |-- README.md |-- NEWS.md ``` --- ## Steps to Create a Package with {fusen} .pull-left[ Install the Fusen package ``` install.packages("fusen") ``` and benefit from a predefined project structure to speed-up package development ] .pull-right[ .img75[] ] --- ## Use a single markdown file to build your package .pull-left[ The {fusen} Rmarkdown template encourages users to fill their documentation and tests at the same time of writing their functions code. {fusen} simplifies and reduces the number of steps towards a full R package. After that, your {pkgdown} documentation website is one command away to be shared with all your users. ] .pull-right[ .img75[] ] --- ## Add a function in your package .pull-left[  ] .pull-right[  ] --- ## Documentation Is Essential Documentation provides information on how to use a package. README.md provides the main pitch for your package Each functions comes with its documentation and an example Vignettes are either like tutorial to quick-start your users or technical documentation explaining how to orchestrate the functions Companion website to be generated with `pkgdown::build_site()` and apply unhcr brand on your website documentation ``` remotes::install_github("unhcr-dataviz/unhcrtemplate") ``` Create a _pkgdown.yml file and Use [unhcrtemplate](https://github.com/unhcr-dataviz/unhcrtemplate) ``` template: package: unhcrtemplate bootstrap: 5 ``` --- ## Add demo data .pull-left[ For users to understand your package and for your to test each functions within your package, you need to provide a demo data set Including a demo dataset in your R package not only enriches user experience but also contributes to the overall accessibility and reliability of your package. There are different ways to do it... ] .pull-right[ ``` MyPackage/ |-- data/ | |-- data_made_available_with_the_package.Rda |-- data-raw/ | |-- data_used_for_package_development.csv |-- inst/ | |-- file_to_be_access_by_the_package.R ``` ] --- ## Managing release * Follow semantic versioning (SemVer) principles. * Increment versions based on changes (major, minor, patch). * Specify the license in your package's DESCRIPTION file. Use MIT license and reference unhcr Alpha Version: * Alpha versions are the earliest stages of software development. * They are typically not feature-complete and may contain many bugs and incomplete features. * Alpha versions are often used for internal testing and may not be released to the public. * Developers use alpha versions to identify and fix major issues. Beta Version: * Beta versions come after alpha versions in the development cycle. * They are more stable than alpha versions but may still contain bugs and issues. * Beta versions are often released to a select group of users for testing, known as beta testers. * Beta testing helps identify issues and gather user feedback before the final release. Release Candidate (RC): * A release candidate is a version of the software that is considered stable and feature-complete. * RC versions are released to a wider audience for testing to ensure there are no major issues. * If no critical bugs are found in the release candidate, it may become the final release. --- ## Package Dev .pull-left[ Checks * Regularly perform package checks using devtools::check(). * Address any warnings, errors, and notes. * Use R CMD check to test your package thoroughly. * Address any issues identified by this tool. * Profile your code with profvis. * Identify bottlenecks and optimize them. Bug Fixes and Updates * Regularly fix reported bugs and update the package. * Keep it compatible with new R releases and dependencies. ] .pull-right[ Robustness * Make your package robust against different inputs. * Handle errors and exceptions gracefully. * Implement thorough unit tests using testthat. * Ensure tests cover the majority of package functionality. Testing on Different Platforms * Set up a CI system (e.g., GitHub Actions, Travis CI). * Automatically run tests on code changes. * Ensure your package works on multiple platforms. * Test compatibility with different R versions. ] --- ## If you want to go fast, go alone, if you want to go far, go together * __Community Engagement__: Engage with the R community and respond to user feedback, Consider contributions from other developers. * __Code of Conduct__: Include a code of conduct in your package to promote an inclusive community. * __Long-Term Maintenance__: Plan for long-term maintenance and have a transition plan in place. * __Peer Review__: Consider having your package peer-reviewed by other R developers. --- ## UNHCRverse https://unhcrverse.r-universe.dev/builds / https://github.com/unhcRverse/unhcRverse.r-universe.dev  ## Conclusion * Creating packages in R is essential for code organization and sharing. * Transition from standalone functions to packages for better code management. * Proper documentation is crucial for effective collaboration and code sharing. --- class: inverse, center, middle # Thank you ### Questions? [post Feedback here](https://github.com/unhcRverse/unhcrverse/issues/new?assignees=&labels=enhancement&projects=&template=comment_prex_2_tidyverse.md&title=%5Blearn%5D) <a href="index.html"><i class="fa fa-indent fa-fw fa-2x"></i></a> --- # Reference - [Hadley - R packages](https://r-pkgs.org/) - [Fusen](https://thinkr-open.github.io/fusen/index.html)